home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / dejagnu.lha / dejagnu-1.0.1 / tcl / doc / CrtCommand.3 < prev    next >
Text File  |  1993-02-14  |  5KB  |  123 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_CreateCommand tcl
  12. .BS
  13. .SH NAME
  14. Tcl_CreateCommand, Tcl_DeleteCommand \- define application-specific command bindings
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  20. .sp
  21. int
  22. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  23. .SH ARGUMENTS
  24. .AS Tcl_CmdDeleteProc (*deleteProc)()
  25. .AP Tcl_Interp *interp in
  26. Interpreter in which to create new command.
  27. .AP char *cmdName in
  28. Name of command to create or delete.
  29. .AP Tcl_CmdProc *proc in
  30. Implementation of new command:  \fIproc\fR will be called whenever
  31. \fIcmdName\fR is invoked as a command.
  32. .AP ClientData clientData in
  33. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  34. .AP Tcl_CmdDeleteProc *deleteProc in
  35. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  36. allows for command-specific cleanup.  If NULL, then no procedure is
  37. called before the command is deleted.
  38. .BE
  39.  
  40. .SH DESCRIPTION
  41. .PP
  42. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  43. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  44. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  45. will call \fIproc\fR
  46. to process the command.  If there is already a command \fIcmdName\fR
  47. associated with the interpreter, it is deleted.  \fIProc\fP should
  48. have arguments and result that match the type \fBTcl_CmdProc\fR:
  49. .nf
  50. .RS
  51. typedef int Tcl_CmdProc(
  52. .RS
  53. ClientData \fIclientData\fR,
  54. Tcl_Interp *\fIinterp\fR,
  55. int \fIargc\fR,
  56. char *\fIargv\fR[]);
  57. .RE
  58. .RE
  59. .fi
  60. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  61. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  62. arguments given to \fBTcl_CreateCommand\fR.
  63. Typically, \fIclientData\fR points to an application-specific
  64. data structure that describes what to do when the command procedure
  65. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  66. the command, \fIargc\fR giving the number of arguments (including
  67. the command name) and \fIargv\fR giving the values of the arguments
  68. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  69. the first \fIargc\fR values point to the argument strings, and the
  70. last value is NULL.
  71. .PP
  72. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  73. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  74. for details on what these codes mean.  Most normal commands will only
  75. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  76. \fIinterp->result\fR to point to a string value;
  77. in the case of a \fBTCL_OK\fR return code this gives the result
  78. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  79. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  80. the return value;  for complete details on how the \fIinterp->result\fR
  81. field is managed, see the \fBTcl_Interp\fR man page.
  82. Before invoking a command procedure,
  83. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  84. commands can return an empty result by doing nothing at all.
  85. .PP
  86. The contents of the \fIargv\fR array are copies made by the Tcl interpreter
  87. for the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
  88. in \fIargv\fR.  However, the \fIargv\fR array
  89. is recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
  90. \fIinterp->result\fR to point anywhere within the \fIargv\fR values
  91. (call Tcl_SetResult
  92. with status \fBTCL_VOLATILE\fR if you want to return something from the
  93. \fIargv\fR array).
  94. .PP
  95. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  96. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  97. or by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
  98. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  99. application an opportunity to release any structures associated
  100. with the command.  \fIDeleteProc\fR should have arguments and
  101. result that match the type \fBTcl_CmdDeleteProc\fR:
  102. .nf
  103. .RS
  104. .sp
  105. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  106. .sp
  107. .RE
  108. .fi
  109. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  110. argument passed to \fBTcl_CreateCommand\fR.
  111. .PP
  112. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  113. Once the call completes, attempts to invoke \fIcmdName\fR in
  114. \fIinterp\fR will result in errors.
  115. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  116. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  117. it returns 0.
  118. There are no restrictions on \fIcmdName\fR:  it may refer to
  119. a built-in command, an application-specific command, or a Tcl procedure.
  120.  
  121. .SH KEYWORDS
  122. bind, command, create, delete, interpreter
  123.